@database VBlank.guide
@$VER: VBlank.guide_english V1.01
@author "J
rg Krause"
@wordwrap
@width 77
@master "VBlank.guide"
@Node Main "VBlank V1.01 - Manual"
    @{fg fill}@{b}VBlank V1.01 - Manual@{ub}@{fg text}
   I.      @{" Synopsis             " Link SYNOPSIS}
   II.     @{" Description          " Link DESCRIPTION}
   III.    @{" Copyright            " Link COPYRIGHT}
   IV.     @{" Author & Support     " Link AUTHOR}
   V.      @{" Purpose & Theory     " Link PURPOSE}
   VI.     @{" Version              " Link VERSION}
   VII.    @{" Starting             " Link STARTING}
   VIII.   @{" Arguments            " Link ARGUMENTS}
   IX.     @{" Tool Types Entries   " Link TOOLTYPES}
   X.      @{" Hot Keys             " Link HOTKEY}
   XI.     @{" Config Window        " Link EDIT}
   XII.    @{" ARexx Interface      " Link REXX}
   XIII.   @{" Commodities Exchange " Link EXCHANGE}
   XIV.    @{" MUI System           " Link MUI}
   XV.     @{" Known Problems       " Link PROBLEMS}
   XVI.    @{" Credits              " Link CREDITS}
@EndNode
@Node SYNOPSIS "VBlank/Synopsis"
@{b}NAME@{ub}
   SYS:WBStartup/VBlank
@{b}Synopsis@{ub}
   VBlank
      @{"CX_PRIORITY/N/K    " Link TOOLTYPES 5}  =<System Priority>
      @{"CX_POPKEY/K        " Link TOOLTYPES 13}  =<@{"Hot Key Description String" Link HOTKEY}>
      @{"CX_POPUP/S         " Link TOOLTYPES 7}  =<No parameter>
      @{"BLANKKEY/K         " Link TOOLTYPES 17}  =<@{"Hot Key Description String" Link HOTKEY}>
      @{"SECONDS=TIMEOUT/N/K" Link TOOLTYPES 21}  =<1 - 3600>
      @{"BLANKMODE/N/K      " Link TOOLTYPES 35}  =<1 - 3>
      @{"JOYSTICK/S         " Link TOOLTYPES 80}  =<YES | NO>
@EndNode
@Node DESCRIPTION "VBlank/Description"
@{b}Description@{ub}
A Screenblanker for the Merlin GFX Card wich uses the
VESA powermanagement. It runs @{i}only@{ui} under Amiga OS
Release 2.04 or newer. Needs the @{"MUI" Link MUI} User-
Interface.
@EndNode
@Node COPYRIGHT "VBlank/Copyright"
@{b}Copyright@{ub}
Copyright 1995 by the Author.
VBlank V1.01 is freely distributable.
VBlank V1.01 is free to be spread on public-domain and
shareware disks especially on Fred Fish's AmigaLibDisks,
as long as they are sold for a reasonable charge that is
less than US $6 or DM 8.- . 
VBlank V1.01  may be distributed on freely available
CD-ROM.   This  CD-ROM should not be used for commercial
obstinacles  like  professional  copyiing.  The price of
the CD-ROM is not important.
For  use  in  commercial  products the permission of the
authors is required.
VBlank V1.01  may  be  copied  and  distributed  via
electronic networks such as the Internet, also it may be
held  available  on anonymous ftp-servers, mail-boxes or
BBS's.
VBlank V1.01 may not, or is not allowed to be used by
any  military institution or any civil institution which
makes any research or products which is used by military
institutions.
@{i}The Copyright is still by the Author.@{ui}
The  author is not responsible for anything which may
happen  to  you,  while using VBlank.  Especially for
any harware problems.
@EndNode
@Node AUTHOR "VBlank/Author & Support"
@{b}Author & Support@{ub}
rg Krause
   Antoniusstr. 19
   33106 Paderborn
   Germany
   INTERNET: quacks@paula.owl.de
   IRC: Quacks
   SUPPORT FTP ADDRESS:
   ftp.uni-paderborn.de [131.234.2.32] anonymous access.
   (Thus any AmiNet site around the world)
   Please  first refer to @{"KNOWN PROBLEMS" Link PROBLEMS}
   below,  before  you  contact  me  for  a Bug-report, any
   comment  is  welcomed  of  course.   Feel free to send a
   donation, some flowers or a postcard.
@EndNode
@Node PURPOSE "VBlank/Purpose & Theory"
@{b}Purpose & Theory@{ub}
VBlank is not yet another screenblanker. VBlank is the first
screenblanker wich supports the VESA powermanagement for the
Merlin GFX Card.
VBlank recognizes the following modes:
  Mode/Status         HSync   VSync   Video     Mode
  ----------------------------------------------------
  "Stand by"          off     on      blank   (mode 1)
  "Suspend"           on      off     blank   (mode 2)
  "Off"               off     off     blank   (mode 3)
@EndNode
@Node STARTING "VBlank/Starting"
@{b}Starting@{ub}
VBlank 1.01 is  a COMMODITY, therefore it @{b}only@{ub} runs
under WB Release 2.0 (V37.175) and newer.
A  Commodity  is  usually  started  in  the  "SYS:WBStartup"
drawer.    So  it  will  be  automatically  started  on  the
workbench startup (LoadWB, usually in "S:Startup-Sequence").
To  get  VBlank  started without rebooting now, double-click
the  icon.   If the Tool Types weren't changed yet, a window
shows  up.   Double-click  once  more, if the window doesn't
show up.
This is the @{"Config Window" Link EDIT} of VBlank.
Now  click  on  the  Gadget  'Hide' or the 'Close-Gadget' to
close the window.
VBlank  is now started.  After 60 seconds the screen will be
blanked,  of  course  only  when  the user doesn't touch the
keyboard or the mouse (or other Input-event's occure).
You  may  start VBlank   from the CLI or another Shell.  For
example you can start VBlank in the S:User-Startup:
    Run >NIL:  <NIL:  VBlank
VBlank supports @{"ReadArgs()" Link "Docs:AutoDocs/dos.hyper/ReadArgs()"}.
For  a  small  help on the command line arguments, start
VBlank with a '?' as Parameter.
@EndNode
@Node ARGUMENTS "VBlank/Arguments"
@{b}Arguments@{ub}
As  every good Commodity, VBlank supports Tool Type entries.
Click  the VBlank.info and press "Right Amiga i" (or use the
Workbench  Menu  Item 'Information') to change or add a Tool
Type entry.
In  fact  this  isn't necessary, as it do supports
@{"Save  Config"  Link  EDIT  107} , which does save all parameters
into the Tool Types of the icon.  You must start VBlank from
the Workbench to enable this feature.
In the ToolType list there are (per default) entered:
    @{"DONOTWAIT        " Link TOOLTYPES   }             # Tell WB to not wait on a return
    @{"CX_PRIORITY      " Link TOOLTYPES 5 }=0           # Priority in "commodities.library"'s queue
    @{"CX_POPUP         " Link TOOLTYPES 7 }             # Show up the window on start
    @{"CX_POPKEY        " Link TOOLTYPES 13}=shift F9    # Config Window Hot Key
    @{"BLANKKEY         " Link TOOLTYPES 1 }=shift F10   # Immediate Blank Hot Key
    @{"TIMEOUT          " Link TOOLTYPES 21}=60          # Time after which VBlank blanks
    @{"BLANKMODE        " Link TOOLTYPES 35}=2           # The VESA Blankingmode
    @{"JOYSTICK         " Link TOOLTYPES 80}=NO          # Enables Joystick support
These  Tool  Types  are the normal way to give arguments for
Commodities  and pure Workbench programs.  Please refer also
to   your   AmigaDOS  Manual  (Section  Workbench  Programms
especially chapter "The WBStartup Drawer") to get an idea of
the Tool Types entries.
@EndNode
@Node TOOLTYPES "VBlank/Tool Types"
@{b}Tool Types@{ub}
   DONOTWAIT
      When started from WBStartup, let WB know that it doesn't
      have  to  wait for VBlank.  Is not a Tool Type entry for
      VBlank, but for te WB.
   CX_PRIORITY=<-128 - 129>
      Priority in "commodities.library"'s input-queue
   CX_POPUP=<NO>
      When  VBlank  is started, the @{"Config Window" Link EDIT}
      may  show  up  when set any (!) other String than 'NO' is
      used.
   CX_POPKEY=<Hot Key>
      Please  see below for the @{"Hotkeys" Link HOTKEY}.  The
      hot key opens the @{"Config Window" Link EDIT} of VBlank.
   BLANKKEY=<Hot Key>
      Please  see below for the @{"Hotkeys" Link HOTKEY}.  The
      hot key immediatly blanks the screen.
   TIMEOUT=<1 - 3600>
      This  is  the  timeout  counter in seconds.  During this
      time NO input from the user must occur in order to start
      the blanker.  Usual time is about 60 secs.
   BLANKMODE= <1 - 3>
      Currently VBlank supports the following Vesa modes:
        Mode/Status         HSync   VSync   Video    Mode
        ----------------------------------------------------
        "Stand by"          off     on      blank   (mode 1)
        "Suspend"           on      off     blank   (mode 2)
        "Off"               off     off     blank   (mode 3)
   JOYSTICK=<YES | NO>
      Toggles   the   joystick  support.   Detects  joystick
      movements as user-activity.
   NOTE:
      The Tool Type Entries should be written in upper-cases.
   NOTE:
      For compatibility reasons, I also support the Tool Type
      'SECONDS' , which is equal to 'TIMEOUT'.  If you use the
      @{"Save Config" Link EDIT 107} option,'TIMEOUT' is used.
@EndNode
@Node HOTKEY "VBlank/Hot Keys"
@KeyWord Hotkey
@{b}Hot Key@{ub}
Refer  to your AmigaDOS Manual (Section The Extras Programs,
The Commodities Drawer) to get a valid list of the available
hot   keys,   the   following   may   obsolete   on   a  new
"commodities.library" version.
The  Hot  Keys  can be edited with the String-Gadgets in the
@{"Config Window  "  Link  EDIT 35} of VBlank.  The syntax and
correctness is checked.
One word for typing the Hot Keys:
In  the  String-Gadget  a  description  of  the  Hot  Key in
textform is beeing asked, not the Hot Key himself.  Thus the
Hot  Key 'left Amiga Key + q' would be typed in as 'lcommand
q'  (all  ten chars inclusive the space).  After the Key was
added to the Commodities Queue, the Hot Key can be activated
by  pressing  and  holding  the  left  Amiga Key followed by
pressing  and  releasing  the 'q' Key and releasing the left
Amiga Key. 
   SYNOPSIS:  [<qualifier> [<qualifier>...]] <key>
       Qualifier keywords (Press and hold one or more qualifier)
       @{b}alt           @{ub}either Alt key
       @{b}ralt          @{ub}right Alt key
       @{b}lalt          @{ub}left Alt key
       @{b}shift         @{ub}either Shift key
       @{b}rshift        @{ub}right Shift key
       @{b}lshift        @{ub}left Shift key
       @{b}capslock      @{ub}Caps Lock key
       @{b}rcommand      @{ub}right Amiga key
       @{b}lcommand      @{ub}left Amiga key
       @{b}control       @{ub}Control key
       @{b}numericpad    @{ub}Enables the use of a key on the numeric keypad
       @{b}rbutton       @{ub}Click (and hold) the right mouse button
       @{b}midbutton     @{ub}Click (and hold) the middle mouse button
                     (only avail for mice with a connected third button!)
       @{b}leftbutton    @{ub}Click (and hold) the left mouse button
       @{b}newprefs      @{ub}Preferences changed
       @{b}diskremoved   @{ub}Disk removed
       @{b}diskinserted  @{ub}Disk inserted
       Keys (to be pressed and released, only ONE Key can be chosen)
       a .. z, 0 .. 9, etc.   Normal keys
       f1 .. f10              Function keys
       up, down, left, right  Cursor keys
       help                   Help key
       del                    Delete key
       return                 Return key
       enter                  Enter key
                   (MUST be combined with 'numericpad'!)
       backspace              Backspace key
       esc                    Escape key
       space                  Space key
       comma                  Comma key
       upstroke               Upstroke key
       Examples
       lalt ralt return
       rcommand f10
       alt x
       lalt numericpad enter
   NOTE:   Choose  your hotkeys @{b}carefully@{ub}, because
   Commodities  have  a  high  priority in the input events
   chain  (i.e.  will override existing definitions).  Also
   some  hotkeys  don't make sense or do collide with other
   tools or functions of the WB.
   NOTE:   The  Workbench screen (or the default PubScreen,
   if  this  one  has  activated the Shanghai-mode) will be
   moved to front before starting the tool via HotKey.
   NOTE:   When  a  combination  of  qualifiers and keys is
   illegal,  VBlank will start, but the Hot Key won't work.
   Example for illegal combinations:
       lalt a b                     # Two keys specified
       control rcommand lcommand    # Reboots the System, Oops!
       lbutton                      # No key specified
   If  you  edit  the Hot Key's in the @{"Config Window" Link   EDIT  35},
   the Combination will be checked.  If invalid, the old Hot
   Key is still used.
   NOTE:   Due  to  a bug in the commodities library, it is
   impossible  to  use  a Mousebutton w/o a Qualifier and a
   Key.(@{"ParseIX()"Link "Docs:AutoDocs/commodities.hyper/ParseIX()"} doesn't set
   the ix_QualMask field right)
   NOTE:   The hot key description strings have been changed
   under Release 3.0 of Workbench.
@EndNode
@Node EDIT "VBlank/Config Window"
@{b}Config Window@{ub}
   When  the  CX_POPUP  is set and VBlank is being
   started  or when the hot key was pressed, a window shows
   up  on  the Workbench.  Normally, the workbench is moved
   to the front.
   You will see some Gadgets.
   The  values  inside the Text-Gadgets are via default set
   to   the   supplied  Arguments  in  the  Tool  Types  or
   CLI-Parameters.   On  a  wrong  Enter, the value will be
   reset to the old value. 
   On  a an enter in the hot key gadgets, the entered string
   will  be  checked  and  if the string is not valid as hot
   key, the old or the default string will be returned.
   You  will  notice,  that some Gadget have names with one
   character  underlined.   The underlined character refers
   to  the  key  on  the keyboard and will alter the entry.
   Use Shift to alter the entry in the other direction.
   @{b}Gadgets:@{ub}
   Keys  in  @{b}bold@{ub}  type are short-cuts.  With them
   you  can access the gadgets with the keyboard w/o moving
   the  mouse.  In Slider- and Cycle-Gadgets, the short-cut
   key will move the slider to the right, use Shift and the
   key to move the slider to the left.
   @{"[T]imeout       " Link TIME  }    @{"[P]op Key  " Link POPKEY  }  @{"[V]esa Mode     " LINK MODE  }
   @{"[H]ide          " Link HIDE  }    @{"[B]lank    " Link BLANK   }  @{"[Q]uit          " Link QUIT  }
   @{b}menu items:@{ub}
   Menu  items  can  also be used via the keyboard, use the
   shown Command Keys.
   @{b}Project-Menu:@{ub}
   Load Config :  Only available on Workbench-Start (either
      Double-Click   or   Sys:WBStartup-drawer).    Loads  the
      Configuration stored in the Tool Types in the Icon.
   Save  Config:  Only available on Workbench-Start.  Saves
      the  actual  (!)  configuration in the Tool Types of the
      Icon.   This  will  overwrite  all  existing  Tool  Type
      Entries.  It's no longer necessary to edit the Tool Type
      Entries.
   About: Shows up the version and Copyright.
   Hide: Hides the Config Window.
   Quit: Exit VBlank.
   @{b}Edit Menu:@{ub}
    Reset To Defaults: Resets all parameters to buildt-in Default Values.
   @{"Overview" Link MAIN}
@EndNode
@Node COMM "VBlank/Config Window/Options"
@{b}Config Windows/Options@{ub}
   Options:
   @{"[T]imeout       " Link TIME  }    @{"[P]op Key  " Link POPKEY  }  @{"[V]esa Mode     " LINK MODE  }
   @{"Overview" Link MAIN} @{"Config Window" Link EDIT}
@EndNode
@Node REXX "VBlank/Rexx Interface"
@{b}Arexx Interface@{ub}
VBlank offers you an Arexx Interface to communicate with
VBlank without opening the Edit Window.  This allows you to
temporarily disable the blanker, to  open  the  Config  Window,
and  of  course  to quit the blanker.
This  is usefull, when a programm is started, which does not
like  VBlank as a screenblanker.
The similarities to the commands to those in the Commodities
Exchange Tool are done for purpose.
The   ARexx-port  is  called  'VBLANK'  and  does  have  the
following commands:
 OPENWINDOW   - Openes the Config Window of VBlank.
 CLOSEWINDOW  - Closes the Config Window, if it was open.
 ENABLE       - Switches the blanker on. From now on all preferences
                will be active.
 DISABLE      - Switches the blanker off. The blanker will not be
                startet. The Rexx-Port will be left accessable.
                This  point is important for games and other
                programms,  which do not like screenblankers
                popping up a screen to the front.
 BLANK        - Immediately starts the blanker.
The MUI system offers you other commands:
 QUIT         - Stops VBlank completely.
 HIDE         - Close or iconify the Config Window.
 SHOW         - Open the Config Window.
 INFO         - Shows you some Information about VBlank,
                please read the MUI-Dokumentation/ARexx.
 HELP         - Shows all Rexx-Commands of VBlank (needs an
                output window, ie. CLI)
SHOW  and HIDE do only function in the presumed way when the
Config  Window  was  already opened once.  Elsewise only the
Icon  will  be  opened and closed.  Onced opened, the Config
Window  will  be iconified with HIDE.  VBlank be closed with
QUIT,   but  the  Icon  will  be  de-iconified,  the  Window
re-opened and then everything will be shut down.  Looks like
a Bug in MUI, it isnt, I want MUI when it is really needed,
not before.
@EndNode
@Node POPKEY "VBlank/Config Window/Pop Key"
@{b}Config Window/Pop Key@{ub}
   [P]op Key=<Hot Key>
      Please  see below for the @{"Hotkeys" Link HOTKEY}.  
      The hot key opens the Config Window of VBlank.
   @{"Overview" Link MAIN} @{"Config Window" Link EDIT}
@EndNode
@Node BLANKKEY "VBlank/Config Window/Blank Key"
@{b}Config Window/Blank Key@{ub}
   Blank [K]ey=<Hot Key>
      Please  see below for the @{"Hotkeys" Link HOTKEY}.  
      The hot key immediatly blanks the screen.
   @{"Overview" Link MAIN} @{"Config Window" Link EDIT}
@EndNode
@Node TIME "VBlank/Config Window/Timeout"
@{b}Config Window/Timeout@{ub}
   [T]imeout: <1 - 3600>
      This  is  the  timeout  counter in seconds.  During this
      time NO input from the user must occur in order to start
      the blanker.  Usual time is about 60 secs.
   @{"Overview" Link MAIN} @{"Config Window" Link EDIT}
@EndNode
@Node MODE "VBlank/Config Window/Vesa Mode"
@{b}Config Window/Vesa Mode@{ub}
   [V]esa Mode: <1 - 3>
   Currently VBlank supports the following Vesa modes:
   Mode/Status         HSync   VSync   Video     Mode
   ----------------------------------------------------
   "On"                on      on      active  (mode 0)
   "Stand by"          off     on      blank   (mode 1)
   "Suspend"           on      off     blank   (mode 2)
   "Off"               off     off     blank   (mode 3)
   @{"Overview" Link MAIN} @{"Config Window" Link EDIT}
@EndNode
@Node JOYSTICK "VBlank/Config Window/Joystick"
@{b}Config Window/Joystick@{ub}
   [J]oystick: <Yes | No>
      Toggles the ckeck for joystick activity.  Only usefull
      for  some  rare  purpose,  ie.  games which are system
      conformant, but don't like a screen popping up (or you
      will loose some highscores :-)
   @{"Overview" Link MAIN} @{"Config Window" Link EDIT}
@EndNode
@Node BLANK "VBlank/Config Window/Blank"
@{b}Config Window/Blank@{ub}
   [B]lank:
      Blank  immediately.   All the new entered values will be
      activated.
   @{"Overview" Link MAIN} @{"Config Window" Link EDIT}
@EndNode
@Node HIDE "VBlank/Config Window/Hide"
@{b}Config Window/Hide@{ub}
   [H]ide:
      Hide  the  window.   All  the new entered values will be
      acivated on the next blank. Of course VBlank is still
      active.
   @{"Overview" Link MAIN} @{"Config Window" Link EDIT}
@EndNode
@Node QUIT "VBlank/Config Window/Quit"
@{b}Config Window/Quit@{ub}
   [Q]uit:
      Exit VBlank.  (Use 'Hide' to close the 'Config Window')
   @{"Overview" Link MAIN} @{"Config Window" Link EDIT}
@EndNode
@Node EXCHANGE "VBlank/Commodities Exchange"
@{b}Commodities Exchange@{ub}
   With  the  Exchange Tool, you can temporarly stop VBlank
   with DISABLE, restart it with ENABLE, remove VBlank with
   KILL  (as  would  do a Quit in the Config Window), SHOW up
   the Config Window, and HIDE the Config Window.
   The  Exchange  Tool  is  a  comfort  way  to  remove  or
   dis/enable VBlank.
   Please  refer  to  the AmigaDOS Manual (Section AmigaDOS
   Reference  and  Workbench Programms) for further docs on
   Exchange Tool.
@EndNode
@Node PROBLEMS "VBlank/Known Problems"
@{b}Known Problems@{ub}
We  do know of some problems and strange behaviours, some of
them aren't strange anymore, when you read this:
-  When  a  disk  is  inserted,  VBlank  closes  the screen
   (dis-blanks).   This  is  normal.   Disk-replacement  is
   detected  as  an input Event.  As all input events shall
   disable  the  Blanker  this  one  should, too.  And this
   event is obvious, the user is alive :-)
-  The  window  doesn't  open  if  the  hotkey  is pressed.
   Perhaps  you  have  supplied a wrong hotkey description.
   Use  the  Commodities  Exchange Tool to open the @{"Edit Window"  Link  EDIT}.
   The  Hot  Key will appear in the  Gadget 'Pop Key'.  You
   can test the hotkey there.  If an  incorrect  hotkey was
   submitted,  the  old hotkey will reappear.
-  VBlank shows up the window though the Tool Type CX_POPUP
   is  set  to  'NO'.   This happens when VBlank is started
   twice.   (Double-click  (or  call  from  CLI)  =  start,
   another  double-click  (or  call  from  CLI)  opens  the
   window).   Please  do  also  check the entries in the MUI
   Preferences.
@EndNode
@Node MUI "VBlank/MUI"
@{b}MUI@{ub}
MUI is a shareware product worth using. It can be found on
the AmiNet or other PD- and Shareware series. 
Without  registering  MUI  the  only  feature  which  is not
available is that you can't save but change the preferences.
Thus MUI _is_ usable even without registration.
Please do read the file @{"'ReadMe.MUI'" Link "ReadMe.MUI"}, which
should be in the Archive.
@EndNode
@Node CREDITS "VBlank/Credits"
@{b}Credits@{ub}
Matthias 'tron' Scheler and Markus 'ill' Illenser for there
ASwarm II (VBlank uses many parts of the source).
Michael 'berti' Brakemeier for his ideas.
@EndNode